Skip to content

docs: add node infrastructure concept page (Batch 2)#210

Merged
marc0olo merged 9 commits into
infra/learn-hub-migration-prepfrom
docs/concepts-node-infrastructure
May 8, 2026
Merged

docs: add node infrastructure concept page (Batch 2)#210
marc0olo merged 9 commits into
infra/learn-hub-migration-prepfrom
docs/concepts-node-infrastructure

Conversation

@marc0olo
Copy link
Copy Markdown
Member

@marc0olo marc0olo commented May 6, 2026

Summary

  • Creates docs/concepts/node-infrastructure.md with full migration of two Learn Hub articles: IC-OS overview (SetupOS, HostOS, GuestOS) and Trusted Execution Environments
  • TEE section covers: SEV-SNP memory encryption, VM launch measurements, attestation reports (including node-to-node and external attestation paths), sealing keys, disk partition layout table (A/B sets, which partitions are encrypted and why), traditional-vs-sealing-key encryption history, HKDF/LUKS key derivation, full 7-step GuestOS upgrade process with Upgrade VM and mutual attestation, and full emergency recovery section (manual rollback with NNS proposal steps + Recovery-GuestOS mechanism with upgrade-vs-recovery comparison table)
  • Adds 3 images from Learn Hub: TEE architecture overview (tee-overview.jpg), SEV-SNP attestation report diagram (tee-attestation-report.svg), SEV-SNP key derivation diagram (tee-key-derivation.svg)
  • Adds concepts/node-infrastructure to the explicit Concepts sidebar after app-architecture
  • Updates docs/concepts/https-outcalls.md: replaces the Learn Hub TEE link with the new internal path; removes a stale Learn Hub further-reading link for the skipped HTTPS Outcalls article

Staging files deleted

  • .migration/learn-hub/how-does-icp-work/node-infrastructure/overview.mddocs/concepts/node-infrastructure.md
  • .migration/learn-hub/how-does-icp-work/node-infrastructure/trusted-execution-environments.mddocs/concepts/node-infrastructure.md#trusted-execution-environments

Sync recommendation

hand-written

@marc0olo marc0olo requested a review from a team as a code owner May 6, 2026 14:57
@marc0olo
Copy link
Copy Markdown
Member Author

marc0olo commented May 6, 2026

Review notes

Content and links look good. One soft dependency to note:

Dependency on #209: The "Further reading" section links to protocol/index.md, which only exists once PR #209 merges. Not a hard build failure, but the link will be dead until then. Consider merging after #209 or temporarily removing the link and adding it back post-merge.

No other issues: no banned patterns, frontmatter complete, Learn Hub TEE link correctly replaced with the internal node-infrastructure.md#trusted-execution-environments path, <!-- Upstream: --> comment present.

@marc0olo
Copy link
Copy Markdown
Member Author

marc0olo commented May 6, 2026

Two items to address before merging:

1. Em-dash on line 89 (banned project-wide)

The "Further reading" bullet uses an em-dash, which is banned per project style rules:

- [Protocol Stack](protocol/index.md) — the replica software that runs inside GuestOS

Fix:

- [Protocol Stack](protocol/index.md): the replica software that runs inside GuestOS

2. Soft dependency on PR #209

The link to protocol/index.md will be a dead link until PR #209 merges and that page exists. Recommend merging this PR after #209 to avoid a temporarily broken link.

@marc0olo
Copy link
Copy Markdown
Member Author

marc0olo commented May 6, 2026

Feedback addressed:

  • Replaced em-dash with colon in node-infrastructure.md line 89 Further reading bullet

Note on the soft dependency: the link to protocol/index.md will still be dead until PR #209 merges. Since #209 is now ready, recommend merging #209 first then this one.

@marc0olo
Copy link
Copy Markdown
Member Author

marc0olo commented May 7, 2026

Brand voice audit applied. The following fixes were committed in 7fe7c79:

Fixed automatically:

  • node-infrastructure.md: expanded NNS on first occurrence ("pushed by the NNS" → "pushed by the Network Nervous System (NNS)")
  • node-infrastructure.md: replaced banned term "workload" ("untrusted workload running in a virtual machine" → "untrusted process running in a virtual machine")

No other brand issues found: no blockchain comparisons, no em-dashes, no "reverse gas model", no DAO, no "on-chain"/"cross-chain"/"full-stack" with hyphens, no "token" used as a primary descriptor.

@marc0olo marc0olo force-pushed the infra/learn-hub-migration-prep branch from dabad66 to d191270 Compare May 8, 2026 09:02
@marc0olo marc0olo force-pushed the docs/concepts-node-infrastructure branch from 30ded57 to 20c2520 Compare May 8, 2026 09:18
@marc0olo
Copy link
Copy Markdown
Member Author

marc0olo commented May 8, 2026

After PR #209 merges:

  1. Add { slug: "concepts/node-infrastructure" } to sidebar.mjs after { slug: "concepts/app-architecture" } in the explicit Concepts items list
  2. Update Further reading to restore: - [Protocol Stack](protocol/index.md): the replica software that runs inside GuestOS

marc0olo added 8 commits May 8, 2026 14:31
Migrates two Learn Hub articles from the "Node Infrastructure" section into
a single docs/concepts/node-infrastructure.md page covering the IC-OS stack
(SetupOS, HostOS, GuestOS) and TEE fundamentals (SEV-SNP memory encryption,
VM launch measurements, attestation, and sealing keys).

Updates docs/concepts/https-outcalls.md: replaces Learn Hub TEE link with
the new internal path and removes a stale Learn Hub further-reading entry.
- Expand NNS to "Network Nervous System (NNS)" on first occurrence
- Replace "untrusted workload" with "untrusted process" (workload is banned vocabulary)
…m Learn Hub

Adds three missing images (TEE overview, attestation report, key
derivation diagrams). Restores content dropped during initial migration:
node-to-node and external attestation paths, encrypted partition names
(var/store vs boot/root/config), HKDF/LUKS key derivation, detailed
GuestOS upgrade process with Upgrade VM and mutual attestation, and the
full emergency recovery section covering manual rollback and the
governance-gated Recovery-GuestOS mechanism.
… encryption history, and full recovery steps

Adds the disk partition layout table (showing which partitions are
encrypted and why), the upgrade-vs-recovery-image comparison table, the
traditional-vs-sealing-key disk encryption context, the full 7-step
manual rollback and Recovery-GuestOS numbered processes, and the
four-feature overview list. Completes the full Learn Hub TEE article
migration.
@marc0olo marc0olo force-pushed the docs/concepts-node-infrastructure branch from f5c8839 to bcbf7f3 Compare May 8, 2026 12:33
…urther reading link

Adds node-infrastructure after app-architecture in the explicit Concepts
sidebar (now that PR #209 has merged). Restores the Protocol Stack
further reading link that was blocked during cross-branch validation.
@marc0olo marc0olo merged commit 072e068 into infra/learn-hub-migration-prep May 8, 2026
3 checks passed
@marc0olo marc0olo deleted the docs/concepts-node-infrastructure branch May 8, 2026 13:21
marc0olo added a commit that referenced this pull request May 11, 2026
## Summary
- Creates `docs/concepts/node-infrastructure.md` with full migration of
two Learn Hub articles: IC-OS overview (SetupOS, HostOS, GuestOS) and
Trusted Execution Environments
- TEE section covers: SEV-SNP memory encryption, VM launch measurements,
attestation reports (including node-to-node and external attestation
paths), sealing keys, disk partition layout table (A/B sets, which
partitions are encrypted and why), traditional-vs-sealing-key encryption
history, HKDF/LUKS key derivation, full 7-step GuestOS upgrade process
with Upgrade VM and mutual attestation, and full emergency recovery
section (manual rollback with NNS proposal steps + Recovery-GuestOS
mechanism with upgrade-vs-recovery comparison table)
- Adds 3 images from Learn Hub: TEE architecture overview
(`tee-overview.jpg`), SEV-SNP attestation report diagram
(`tee-attestation-report.svg`), SEV-SNP key derivation diagram
(`tee-key-derivation.svg`)
- Adds `concepts/node-infrastructure` to the explicit Concepts sidebar
after `app-architecture`
- Updates `docs/concepts/https-outcalls.md`: replaces the Learn Hub TEE
link with the new internal path; removes a stale Learn Hub
further-reading link for the skipped HTTPS Outcalls article

## Staging files deleted
-
`.migration/learn-hub/how-does-icp-work/node-infrastructure/overview.md`
→ `docs/concepts/node-infrastructure.md`
-
`.migration/learn-hub/how-does-icp-work/node-infrastructure/trusted-execution-environments.md`
→ `docs/concepts/node-infrastructure.md#trusted-execution-environments`

## Sync recommendation
hand-written

<!-- Upstream: informed by Learn Hub articles "Overview" (Node
Infrastructure), "Trusted Execution Environments" (migrated, source
retired) -->
raymondk pushed a commit that referenced this pull request May 11, 2026
…ocs (#208)

## Summary

Migrates all 57 developer-relevant articles from the Learn Hub \"How
does ICP work?\" section into the developer docs, replacing Learn Hub as
the canonical source for ICP protocol concepts before the site is
retired.

This was executed as 9 content batch PRs plus a post-migration review
pass, all merged into this staging branch before landing on `main`:

**Batch 1 — Protocol stack** (#209): Consensus, peer-to-peer, message
routing, execution layer, state synchronization, and performance concept
pages under `docs/concepts/protocol/`.

**Batch 2 — Node infrastructure** (#210):
`docs/concepts/node-infrastructure.md` — TEE (SEV-SNP) attestation,
IC-OS layer model (SetupOS / HostOS / GuestOS), TEE key derivation and
disk encryption.

**Batch 3 — Edge infrastructure** (#211):
`docs/concepts/edge-infrastructure.md` — boundary nodes, HTTP gateway,
edge caching.

**Batch 4 — Evolution and scaling** (#212):
`docs/concepts/evolution-scaling.md` — horizontal scaling via subnet
sharding, fault tolerance, governance-driven subnet creation, forkless
protocol upgrades.

**Chain fusion deep dives** (#213): Expanded
`docs/concepts/chain-fusion/` with dedicated pages for Bitcoin
integration, ckBTC mechanics, Ethereum integration, EVM RPC, Solana RPC,
Dogecoin integration, and Exchange Rate Canister. Architecture and flow
diagrams migrated to `public/concepts/chain-fusion/`.

**Cryptography deep dives** (#214): Expanded
`docs/concepts/chain-key-cryptography.md` and
`docs/concepts/certified-data.md` with subnet keys, threshold signing
internals, and certified communication theory.

**Tokens, ledgers, and cycles** (#215): Expanded
`docs/concepts/ledgers.md` and `docs/concepts/cycles.md` with ledger
architecture, accounts, sub-accounts, cycles ledger transfer semantics,
and NNS tokenomics.

**Governance deep dives** (#216): Expanded `docs/concepts/governance.md`
and added `docs/concepts/sns-framework.md` — NNS neuron attributes and
bonuses, voting rewards formula, Neurons Fund, proposal taxonomy, SNS
framework and architecture, DAO settings, launch flow, SNS neurons and
rewards, and SNS proposals.

**Principals and canister model** (#217): Expanded
`docs/concepts/principals.md` and `docs/concepts/canisters.md` —
principal model, canister control, Wasm execution model, and
`docs/concepts/app-architecture.md`.

**Post-migration holistic review** (#218, #226):
- Navigation restructured across all concepts, guides, and references —
sentence case applied throughout, section indices completed
- Cross-reference audit: all Learn Hub outbound links replaced with
internal doc links; first-use terms linked to their concept pages
- Glossary expanded with TEE, boundary node, and cycle-related entries
- System canisters content placement corrected
- Exchange Rate Canister restructured across concept, reference, and
guide pages (#XRC commits)

**Migration infrastructure** (initial prep commits):
- `.docs-plan/learn-hub-migration.md` — agent workflow and authoring
rules for 9-batch execution
- `.docs-plan/learn-hub-navigation.md` — per-article mapping (target
file, action type, cross-link table)
- `AGENTS.md / CLAUDE.md` — Learn Hub removed from external-docs list;
linking rule updated
- `sidebar.mjs` — all new concept pages registered

## Closes

- Closes #187 — Content gap analysis: Learn Hub vs developer docs
- Closes #190 — Gap analysis: articles on learn.internetcomptuter.org vs
developer-docs `reference` and `concepts`
- Closes #226 — Post-migration holistic review (content placement, nav
structure, glossary, first-use terms)

## Sync recommendation

hand-written (all pages authored from Learn Hub source articles via
Zendesk API; no upstream repo to sync from)

<!-- Upstream: source articles fetched from learn.internetcomputer.org
via Zendesk API (2026-05-06 through 2026-05-11) -->
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant